Add method-based TagLib syntax with legacy compatibility, benchmarks, and docs by davydotcom · Pull Request #15465 · apache/grails-core

davydotcom · 2026-02-26T13:01:17Z

Summary

This PR introduces method-based TagLib handlers as the recommended syntax, while preserving full backward compatibility with closure-based handlers and legacy invocation paths.

Rebased onto 8.0.x from the original PR #15459.

What's included

Add method-defined TagLib support in core dispatch/invocation paths
Preserve implicit method context (attrs and body) for method handlers
Support binding named attributes directly to method signature arguments (for example def greeting(String name) binds from name="...")
Add compatibility shims so legacy property/direct invocations continue to work for method-defined tags
Preserve namespaced dispatch behavior and collision handling with method-backed tags
Add compile-time warning for closure-defined tag fields in user TagLibs
Convert shipped Grails web/GSP taglibs to method-based handlers
Add coverage for method-defined tags and legacy compatibility behavior
Add benchmark spec for method vs closure invocation
Update guides/docs to present method syntax first, with closure syntax as legacy-compatible

Performance

The method-vs-closure benchmark added in this change set shows an approximately 7–10% improvement for method-based invocation in the covered scenarios.

TagLib syntax examples

Recommended (method-based)

class DemoTagLib {
    static namespace = 'demo'

    def greet() {
        out << "Hello, ${attrs.name}!"
    }

    def greeting(String name) {
        out << "Hello, ${name}!"
    }

    def repeat() {
        attrs.times?.toInteger()?.times { n ->
            out << body(n)
        }
    }
}

Usage:

<demo:greet name="Ada" />
<demo:greeting name="Ada" />

Legacy-compatible (closure field)

class DemoTagLib {
    static namespace = 'demo'

    def greet = { attrs, body ->
        out << "Hello, ${attrs.name}!"
    }
}

Validation performed

Focused regressions:
- FormTagLib2Tests
- FormTagLib3Tests
- SelectTagTests
- NamespacedTagLibMethodTests
- TagLibMethodMissingSpec
- MethodDefinedTagLibSpec
Full suite:
- :grails-gsp:test
Functional validation:
- :grails-test-examples-app1:integrationTest --tests functionaltests.MiscFunctionalSpec

Co-Authored-By: Oz oz-agent@warp.dev

…pdate - implement method-defined tag handler support and invocation context - preserve closure-style behavior across property/direct and namespaced paths - convert built-in web/GSP taglibs to method syntax - add compile-time warning for closure-defined tag fields - add coverage and benchmark for method vs closure invocation - update guides and demo taglib samples to method syntax Co-Authored-By: Oz <oz-agent@warp.dev>

Co-Authored-By: Oz <oz-agent@warp.dev>

- treat only Map parameter named attrs as full tag attributes map - allow other Map-typed parameters to bind from attribute key by parameter name - add regression tests for map-valued attribute binding and reserved attrs behavior Co-Authored-By: Oz <oz-agent@warp.dev>

- use private implementation helpers to avoid recursive dispatch in typed overloads - keep Map-based handlers for validation-safe fallback behavior - add regression test ensuring private/protected methods are not exposed as tag methods - document overload pattern for typed signatures with existing validation paths Co-Authored-By: Oz <oz-agent@warp.dev>

…gnment - keep typed overloads delegating to private implementation helpers - remove unnecessary attrs.name writes since typed args are sourced from attrs - preserve behavior validated by focused FormTagLib and method-tag test suites Co-Authored-By: Oz <oz-agent@warp.dev>

- add thread-safe ClassValue cache for invokable public tag methods by name - remove per-invocation getMethods scans in hasInvokableTagMethod/invokeTagMethod - optimize TagLibrary.propertyMissing by caching method fallback closures in non-dev mode - use resolved namespace for default-namespace fallback closures Co-Authored-By: Oz <oz-agent@warp.dev>

- restore attrs-reserved binding for paginate - route namespaced method tag calls via tag output capture - add fieldValue(Map) compatibility overload - harden form fields rendering/raw handling with method dispatch Co-Authored-By: Oz <oz-agent@warp.dev>

jamesfredley · 2026-02-26T14:28:18Z

Doc Examples

Files: namespaces.adoc, tagReturnValue.adoc
In namespaces.adoc, the new method-based tag was added but the old closure-based tag was also left in place, :

class SimpleTagLib {
    static namespace = "my"
    def example() {        // ← new method added
    def example = { attrs ->  // ← old closure NOT removed
        //...
    }

Same issue in tagReturnValue.adoc - def content() was inserted but def content = { attrs, body -> remains on the next line. Both are incomplete edits that will produce broken examples in the published docs.

`isTagMethodCandidate` Is Broad

Any public, non-static, non-getter/setter method on a TagLib class is treated as a tag candidate. The exclusion list is minimal:

afterPropertiesSet
get*() (zero-arg) / set*(x) (one-arg)
invokeMethod, methodMissing, propertyMissing
Methods declared on Object or GroovyObject
This means toString(), hashCode(), equals(), other Spring lifecycle methods (e.g. destroy(), onApplicationEvent()), and any custom utility methods will all be registered as invokable tags. A TagLib with a helper method like def formatDate(Date d) would silently become a <g:formatDate> tag.

Namespace Property Guard Removed

registerNamespaceMetaProperty previously had a guard:

if (!metaClass.hasProperty(namespace) && !doesMethodExist(metaClass, getGetterName(namespace), ...)) {
    registerPropertyMissingForTag(...)
}

That guard was removed - namespace dispatchers now always overwrite. This could shadow real properties on TagLibs that happen to share a name with a registered namespace (e.g. a TagLib with a String my property when "my" is also a namespace).

`registerTagMetaMethods` Now Defaults `overrideMethods = true`

The signature changed to:

static void registerTagMetaMethods(MetaClass emc, TagLibraryLookup lookup, String namespace, boolean overrideMethods = true)

For the taglib's own namespace, tags now always override existing metaclass methods, whereas previously overrideMethods was false. This could break TagLibs that intentionally define a method sharing a name with a default-namespace tag (the local method would get silently overwritten by the tag dispatcher).

ThreadLocal Push Outside `try` Block

In GroovyPage.invokeTagLibMethod():

TagMethodContext.push(attrs, actualBody);          // ← outside try
Object tagResult = TagMethodInvoker.invokeTagMethod(tagLib, tagName, attrs, actualBody);
outputTagResult(returnsObject, tagResult);
} finally {
    TagMethodContext.pop();                         // ← inside finally

If an exception occurs between push() and the try block (or if invokeTagMethod throws before entering the try), the push has already happened but pop may not execute in the right scope. The push should be moved inside the try to guarantee the finally always cleans up exactly what was pushed.

Single-Parameter Fallback Heuristic in `toMethodArguments`

When a tag method has a single parameter and attrs has a single entry, the code uses the first value from the map regardless of whether the parameter name matches:

if (value == null && parameters.length == 1 && attrs != null && attrs.size() == 1) {
    value = attrs.values().iterator().next();
}

This is a magic heuristic that could silently bind the wrong attribute. For example, <g:myTag foo="bar"/> calling def myTag(String name) would bind "bar" to name even though the attribute is foo, not name. This makes debugging attribute-binding issues difficult.

…egistered as tag methods Make helper methods private across all affected TagLib files to prevent TagMethodInvoker.isTagMethodCandidate() from matching them as tag methods. Remove convenience overloads (e.g. textField(String,Map)) entirely where Groovy 4's multimethod restriction forbids mixing private/public methods of the same name. Changes: - ApplicationTagLib: make renderResourceLink, doCreateLink private - FormatTagLib: make messageHelper private - UrlMappingTagLib: make appendClass private - ValidationTagLib: remove fieldValue(Map) overload, make formatValue private, remove formatValue from returnObjectForTags - FormTagLib: remove 5 typed convenience overloads, make renderNoSelectionOption private - FormFieldsTagLib: make 9 protected helper methods private - TagMethodInvoker: sort methods by descending param count to prefer (Map,Closure) over (Map) signatures - Checkstyle/CodeNarc fixes: alphabetical imports, blank lines before constructors, single-quoted strings

# Conflicts: # grails-fields/grails-app/taglib/grails/plugin/formfields/FormFieldsTagLib.groovy # grails-gsp/plugin/src/main/groovy/org/grails/plugins/web/taglib/ApplicationTagLib.groovy # grails-gsp/plugin/src/main/groovy/org/grails/plugins/web/taglib/FormTagLib.groovy

jdaugherty · 2026-04-25T16:31:50Z

@davydotcom I made some attempts at fixing the test pollution, but I think there is still more work required here.

jdaugherty · 2026-04-25T16:34:09Z

From my AI Results:

  1. Generic test-isolation fix at the Spock extension level                                                                                                                                                       
                                                                                                                                                                                                                     
    Tests using UrlMappingsUnitTest no longer need per-test cleanup boilerplate. The fix lives in three places:                                                                                                      
                                                                                                                                                                                                                     
    - grails-testing-support-web/src/main/groovy/grails/testing/web/UrlMappingsUnitTest.groovy — mockArtefact() now clears artefactInfo and destroys the cached grailsUrlMappingsHolder singleton before
    re-registering. Added resetUrlMappingsForFeature() and cleanupUrlMappingsAfterFeature() helpers.                                                                                                                 
    - grails-testing-support-web/src/main/groovy/org/grails/testing/spock/UrlMappingSetupSpecInterceptor.groovy — now handles both setupSpec (mocking controllers) and setup (re-registering URL mappings before each
     feature method).                                                                                                                                                                                                
    - grails-testing-support-web/src/main/groovy/org/grails/testing/spock/UrlMappingCleanupInterceptor.groovy (new) — clears the URL mapping artefact registry after each feature method so non-UrlMappingsUnitTest
    specs running later in the same JVM don't inherit foreign mappings.                                                                                                                                              
    - grails-testing-support-web/src/main/groovy/org/grails/testing/spock/WebTestingSupportExtension.groovy — wires the new setup/cleanup interceptors.
    - grails-gsp/plugin/src/test/groovy/org/grails/web/mapping/RestfulReverseUrlRenderingTests.groovy — removed the now-redundant per-test setup/cleanup workaround.

jdaugherty · 2026-04-25T16:34:22Z

Concerning the continued failures:

Original CI failures (5 tests at maxTestParallel=3, 1 test at maxTestParallel=4) are reduced to occasional flakes on ReverseUrlMappingToDefaultActionTests.testLinkTagRendering. That remaining flake is a
pre-existing URL-mapping selection issue in DefaultUrlMappingsHolder — the holder contains the right mappings (verified via debug) but the lookup intermittently picks /$id? over /$dir/$id?. It's unrelated to
the test-isolation problem the PR's CI was hitting.

jdaugherty · 2026-04-27T00:34:53Z

Update on this, from the AI:

          ⏺ The smoking gun! ReverseUrlMappingTests' setup updated linkGen=1573001442 but the test is using linkGen=1931205834 (from RestfulReverseUrlRenderingTests). Tag library state is shared across specs.

So the tag library state isn't being cleaned up correctly.

Here's the code it used:

# Conflicts: # DEVELOPMENT.md # grails-gsp/plugin/src/main/groovy/org/grails/plugins/web/taglib/ApplicationTagLib.groovy # grails-gsp/plugin/src/main/groovy/org/grails/plugins/web/taglib/FormTagLib.groovy

jdaugherty · 2026-04-29T00:06:14Z

I believe I've addressed all of @jamesfredley 's comments.

jdaugherty · 2026-04-29T03:16:41Z

I decided to move the taglib cleanup to be by feature instead of by spec. The biggest reason was the flakiness of the grails-gsp test run was really due to partial clean-ups. By cleaning up after each feature, each test is isolated.

# Conflicts: # build-logic/docs-core/build.gradle # build.gradle # grails-forge/build.gradle # grails-gradle/build.gradle

testlens-app · 2026-05-04T04:42:04Z

✅ All tests passed ✅

⚠️ TestLens detected flakiness ⚠️

Test Summary

Check	Project/Task	Test	Runs
CI / Functional Tests (Java 25, indy=false)	:grails-test-examples-app1:integrationTest	AsyncPromiseSpec > conditional async uses sync mode when requested	❌ ✅

🏷️ Commit: 38d41c8
▶️ Tests: 7179 executed
⚪️ Checks: 34/34 completed

Learn more about TestLens at testlens.app.

codeconsole

Nice work!

Considerations?:

PR #15465 Review — Method-based TagLib Handlers

Substantial, well-thought refactor (+1401/-244, ~60 files). The ClassValue cache, push/pop discipline in
GroovyPage.invokeTagLibMethod, and the UrlMappingsUnitTest.mockArtefact fix are good. Highest-impact
issues below.

Blockers

B1 — TagMethodInvoker.invokeTagMethod swallows Error and rewraps it as RuntimeException. The
catch only handles RuntimeException; an Error (StackOverflowError, AssertionError) gets boxed, hiding
the true cause. Add if (target instanceof Error err) throw err; and prefer GrailsTagException
(consistent with the closure path) for non-runtime targets.

B2 — Closure-tag dispatch regresses. TagMethodInvoker.getClosureTagProperty walks the superclass
chain via getDeclaredField on every closure tag invocation, replacing what was previously a single
metaclass getProperty(tagName). Tag-heavy GSPs likely take a hit on the closure path that the benchmark
doesn't measure. Cache resolved fields in a ClassValue<Map<String, Optional<Field>>> mirroring
INVOKABLE_METHODS_BY_NAME.

B3 — TagLibArtefactTypeAstTransformation deprecation warning is unconditional. Third-party plugins
that ship closure-defined tag fields will spam warnings during user compilation, with no opt-out. Verify
whether GrailsASTUtils.warning interacts with Groovy's Werror flag — if so this can break user builds.
Gate behind a system property (grails.taglib.warnDeprecatedClosures) and/or skip when the source is from
a plugin jar, not the user's app.

Major

M1 — ValidationTagLib.formatValue silently dropped from returnObjectForTags and made private.
<g:formatValue> was a public tag; this is a breaking behavior change not called out in
upgrading80x.adoc. Either restore it as a public method tag, or document the removal.

M2 — toMethodArguments returns null (rejecting the overload) when any non-attrs/non-Closure arg
is null. Closures pass null through; typed-parameter tags now silently fall through to another
overload or throw MissingMethodException. Only reject null when the parameter is primitive; allow it
for reference types.

M3 — Method resolution depends on JVM-defined getDeclaredMethods() order for same-arity overloads.
Add a deterministic tiebreaker (e.g., parameter-type names) so behavior is identical on HotSpot vs.
Graal/J9.

M4 — is*() no-arg exclusion is heuristic-fragile. Targeted at JavaBean accessors, but a tag
legitimately written boolean isAvailable(...) works only because it has args. Consider a @Tag
annotation override for explicit opt-in.

Minor / DRY

N1 — FormTagLib private *Impl helpers (textFieldImpl, passwordFieldImpl, submitButtonImpl,
etc.) are ~30 lines of mechanical boilerplate caused by the Groovy 4 multimethod restriction. A single
private void renderField(Map attrs, String type) setting both attrs.type and attrs.tagName collapses
them.
N2 — UrlMappingTagLib.paginate: attrs = (TypeConvertingMap) attrs re-casting the parameter to
itself is non-obvious; introduce a typed local.
N3 — JavascriptTagLib.javascript/escapeJavascript not converted while everything around them is —
introduce a typed local.
N3 — JavascriptTagLib.javascript/escapeJavascript not converted while everything around them is — either convert or
add a one-line comment about why.
N4 — Doc examples in simpleTags.adoc and MethodDefinedTagLibSpec reference
propertyMissing('attrs')/propertyMissing('body'). CLAUDE.md says don't expose internal mechanisms in docs — add a public
currentAttrs()/currentBody() helper on the TagLibrary trait and document that.
N5 — TagMethodContext.ThreadLocal is only remove()d when the stack empties on pop. If any dispatch path ever skips
pop, a later request on the same container thread sees stale attrs/body. Add a request-lifecycle interceptor that calls
clearAll() defensively.
N6 — FRAMEWORK_METHOD_NAMES and NON_TAG_METHOD_NAMES overlap conceptually; consolidate to avoid drift.
N7 — Test deletions (RestfulReverseUrlRenderingTests -22, etc.) are not coverage losses — they're redundant after
UrlMappingCleanupInterceptor and the new mockArtefact cleanup. Good DRY.

Positives

ClassValue is the right primitive for class-keyed caches (auto-invalidates on unload).
try/finally push/pop in GroovyPage.invokeTagLibMethod is correct.
Benchmark spec is honest — prints, doesn't assertion-gate the percentage.
mockArtefact destroys the cached singleton before re-registering — fixes a real test-isolation hazard.

Recommendation

Fix B1, B2, B3, M1, M2 before merge; the rest are post-merge improvements. The formatValue removal (M1) is the most likely to
bite real users silently

davydotcom and others added 8 commits February 26, 2026 07:55

Document typed attribute-to-argument binding for method TagLib syntax

106c92c

Co-Authored-By: Oz <oz-agent@warp.dev>

Add typed method-argument TagLib example to simple tags guide

1d708b1

Co-Authored-By: Oz <oz-agent@warp.dev>

davydotcom added feature documentation labels Feb 26, 2026

github-project-automation Bot added this to Apache Grails Feb 26, 2026

davydotcom and others added 8 commits February 26, 2026 13:56

fixing more issues with testing

6683ca6

missing some methods

e53430a

styling: fix import order

c3b4cf0

Fix raw lookup to be CompileStatic

c1db2b3

feature - ability to rerun tests without having to rerun all tasks

5103ee3

Test pollution fixes & cleanup

c1d07b0

jdaugherty added 6 commits April 26, 2026 20:47

Attempting to fix test pollution

b7a7a5f

Merge branch '8.0.x' into feature/taglib-method-actions

5680d19

# Conflicts: # DEVELOPMENT.md # grails-gsp/plugin/src/main/groovy/org/grails/plugins/web/taglib/ApplicationTagLib.groovy # grails-gsp/plugin/src/main/groovy/org/grails/plugins/web/taglib/FormTagLib.groovy

Prevent test pollution

567d14d

Fix is* invocations

1ce4322

Adjust code style

9d1c76b

Always clear taglib metaclasses in web test cleanup

531150c

jdaugherty added 4 commits April 28, 2026 20:01

Tighten method tag dispatch and preserve taglib remocking

68a4049

Document Grails 8 taglib updates

06c93bf

Codestyle fixes

9ef3130

Merge branch '8.0.x' into feature/taglib-method-actions

79d4d0b

jdaugherty added 5 commits April 28, 2026 20:28

Restore taglib namespace lookups after web cleanup

bad5577

Fix calling a taglib directly

5f439ec

Merge branch '8.0.x' into feature/taglib-method-actions

d8b13a0

Remove unused import

2e8ab1f

Move taglib mocks to setup() instead of setupSpec()

9ab3547

jdaugherty added 2 commits May 3, 2026 20:49

Merge branch '8.0.x' into feature/taglib-method-actions

4017fe0

# Conflicts: # build-logic/docs-core/build.gradle # build.gradle # grails-forge/build.gradle # grails-gradle/build.gradle

Update rat-config for generated files

20e515d

jdaugherty requested review from codeconsole and jamesfredley May 4, 2026 00:54

Fix bad merge

38d41c8

codeconsole requested changes May 4, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add method-based TagLib syntax with legacy compatibility, benchmarks, and docs#15465

Add method-based TagLib syntax with legacy compatibility, benchmarks, and docs#15465
davydotcom wants to merge 34 commits into8.0.xfrom
feature/taglib-method-actions

davydotcom commented Feb 26, 2026

Uh oh!

jamesfredley commented Feb 26, 2026

Uh oh!

jdaugherty commented Apr 25, 2026

Uh oh!

jdaugherty commented Apr 25, 2026

Uh oh!

jdaugherty commented Apr 25, 2026

Uh oh!

jdaugherty commented Apr 27, 2026 •

edited

Loading

Uh oh!

jdaugherty commented Apr 29, 2026

Uh oh!

jdaugherty commented Apr 29, 2026

Uh oh!

testlens-app Bot commented May 4, 2026 •

edited

Loading

Uh oh!

codeconsole left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

davydotcom commented Feb 26, 2026

Summary

What's included

Performance

TagLib syntax examples

Recommended (method-based)

Legacy-compatible (closure field)

Validation performed

Uh oh!

jamesfredley commented Feb 26, 2026

Doc Examples

isTagMethodCandidate Is Broad

Namespace Property Guard Removed

registerTagMetaMethods Now Defaults overrideMethods = true

ThreadLocal Push Outside try Block

Single-Parameter Fallback Heuristic in toMethodArguments

Uh oh!

jdaugherty commented Apr 25, 2026

Uh oh!

jdaugherty commented Apr 25, 2026

Uh oh!

jdaugherty commented Apr 25, 2026

Uh oh!

jdaugherty commented Apr 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jdaugherty commented Apr 29, 2026

Uh oh!

jdaugherty commented Apr 29, 2026

Uh oh!

testlens-app Bot commented May 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ All tests passed ✅

Test Summary

Uh oh!

codeconsole left a comment

Choose a reason for hiding this comment

PR #15465 Review — Method-based TagLib Handlers

Blockers

Major

Minor / DRY

Positives

Recommendation

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

`isTagMethodCandidate` Is Broad

`registerTagMetaMethods` Now Defaults `overrideMethods = true`

ThreadLocal Push Outside `try` Block

Single-Parameter Fallback Heuristic in `toMethodArguments`

jdaugherty commented Apr 27, 2026 •

edited

Loading

testlens-app Bot commented May 4, 2026 •

edited

Loading